Skip to content

Move repeated inline page scripts, styles, and icons into shared assets - #2216

Merged
David Pine (IEvangelist) merged 5 commits into
mainfrom
dapine-microsoft-externalize-inline-page-assets
Nov 20, 2026
Merged

David Pine (IEvangelist) merged 5 commits into
mainfrom
dapine-microsoft-externalize-inline-page-assets

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Summary

This PR is part of a series to cut the size of the frontend container image, which is currently about 4 GB. CI run 44388682589 produced 38,344 HTML pages totaling 9.4 GB. A typical docs page carries about 85 KB of inline SVG, 48 KB of inline script, and 13 KB of inline CSS, and every page repeats that markup. This PR moves it into shared, hashed /_astro/ assets that StaticHost already caches as immutable.

  • Head scripts: the AppHost-language/sidebar preference bootstrap and the WCP consent bootstrap moved to hashed files in src/scripts/*.inline.js, loaded with ?url.
    • The preference bootstrap (~4.5 KB) stays a render-blocking <script is:inline src>. It has to set data-apphost-lang and the sidebar-collapsed attributes before first paint.
    • The WCP bootstrap (~14 KB) now loads with defer, because it only needs the parsed DOM. Its one pre-paint step, hiding cookie controls when a previous visit found consent isn't required, is a ~200-byte inline snippet.
    • Consent still initializes before analytics, and the WCP CDN script is still loaded live.
    • Why not inline the bootstraps again: that would put ~19 KB back into all ~38k pages (~700 MB). The cost of keeping them external is one small render-blocking request on a first visit; after that the file comes from the immutable /_astro/ cache.
  • Footer and OsAwareTabs: both now use bundled Astro <script>s. Each OsAwareTabs renders a hidden data-os-aware-tabs-sync-key marker that the shared module src/scripts/os-aware-tabs.ts reads.
  • Build config: sets build.inlineStylesheets: 'never'. Also sets vite.build.assetsInlineLimit so JavaScript and the icon sprite are never inlined. Astro had been inlining about 10–12 KB of small module scripts into every page.
  • Sidebar caret and page-action external-link icon: both are now CSS masks, added to the existing Starlight and starlight-page-actions patches. They look the same, stay aria-hidden, and have a forced-colors fallback. Sidebar structure and data are unchanged.
  • Icon sprite: config/starlight-icon-sprite.mjs redirects every import of Starlight's Icon to src/components/starlight/Icon.astro. That wrapper serves 40 common icons from a 24 KB hashed sprite through <use>; any other icon still renders inline. bun run icon-sprite regenerates the sprite, and a unit test fails if it drifts from the installed Starlight icon set. Icons that fall back to inline markup keep the caller's class; a unit test covers this.

Estimated savings, measured against live aspire.dev pages:

  • Docs page (get-started/install-cli/, 266 KB): about 93 KB less (~35%).
  • API page (reference/api/csharp/aspire.hosting/, 1.53 MB): about 180 KB less (~12%). About 108 KB of that comes from the 390 sidebar carets.
  • Site-wide: very roughly 3.5–6 GB of HTML. This is an estimate; the CI build will give the real number.

Expected merge conflicts with other PRs in the series:

  • src/frontend/patches/@astrojs__starlight@0.41.3.patch will conflict with the locale-fallback PR.
  • src/frontend/.starlight-icons/safelist.json will conflict with the C# API sidebar PR. That file is regenerated, so regenerate it after merging.

Behavior notes:

  • The removed Footer external-link script called Astro.locals.t in the browser. That call always threw, so it never added the "(opens in new tab)" aria-label. I dropped the dead code; the external links' target and rel behavior is unchanged.
  • First-time visitors on Windows may briefly see the Bash tab before it switches to PowerShell. The OS default now runs from a module script after the page is parsed, not from an inline script.

Third-party links and affiliations

None

Validation

Everything below ran locally. I did not run bun run build locally (it's left to CI), so this PR's CI build is the first full build with these changes.

  • bunx vitest run --config vitest.config.ts (full unit suite) — passed (1,488 passed, 1 skipped) after the main changes. One assertion was then updated.
  • bunx vitest run --config vitest.config.ts tests/unit/icon-sprite.vitest.test.ts tests/unit/custom-components.vitest.test.ts — passed (129/129) after that final change.
  • bunx vitest run --config vitest.config.ts tests/unit/navigation-preferences.vitest.test.ts tests/unit/navigation-theme.vitest.test.ts tests/unit/page-weight-guardrails.vitest.test.ts tests/unit/custom-components.vitest.test.ts — passed (136/136).
  • bunx eslint <changed files> --max-warnings 0 and bunx prettier --check on new and changed files — passed. Running ESLint over all of src/scripts also reports errors in the untouched deployment-guard.ts and tooltips.ts.
  • bunx playwright test tests/e2e/cookie-consent.spec.ts tests/e2e/ui-regressions.spec.ts tests/e2e/mobile-ux.spec.ts tests/e2e/site-ui-navigation.spec.ts --workers=2, run against astro dev — 142 passed, 5 failed, 42 skipped. The failures were dev-server timeouts, connection resets, and 503s.
  • Rerunning those 5 tests with --workers=1: 4 passed. ui-regressions.spec.ts:797 ("aligns the scroll-to-top control…") failed once more, then passed when run alone on desktop-chromium. It looks flaky, but I didn't recheck it on the other viewports, so please watch it in CI.
  • site-ui-navigation.spec.ts with --repeat-each=3 on all projects — passed.
  • Follow-up fixes found by testing in the combined aspire publish image:
    • api-search-contract.spec.ts:248 was holding every script request until it had typed into the search box. The blocking head bootstrap stops HTML parsing, so the search box never appeared and the test deadlocked. The test now holds back only module scripts (the search controller), which is what it's meant to test. bunx playwright test tests/e2e/api-search-contract.spec.ts:248 --repeat-each=2 — passed (6/6). It failed once on the cold first run of the dev server.
    • bunx playwright test tests/e2e/live-status.spec.ts:703 tests/e2e/cookie-consent.spec.ts --workers=1 — passed.
    • bunx vitest run --config vitest.config.ts tests/unit/icon-sprite.vitest.test.ts tests/unit/navigation-preferences.vitest.test.ts tests/unit/navigation-theme.vitest.test.ts tests/unit/custom-components.vitest.test.ts — passed (135/135). The new icon-class assertion fails without the fix.
  • I checked the dev server in a browser. The sidebar carets, the "Open" dropdown, the footer, and the sprite icons render correctly; no asset requests failed; the consent and preference scripts load as external files; and the OsAwareTabs default applies.

- Load the AppHost preference and WCP consent bootstraps as blocking,
  hashed /_astro/ scripts instead of inlining them in every page.
- Bundle the Footer and OsAwareTabs scripts; OsAwareTabs now renders a
  marker read by a shared module.
- Emit all JavaScript as files (no inline module scripts) and set
  build.inlineStylesheets to 'never'.
- Render the sidebar caret and page-action external icon via CSS masks
  (Starlight / starlight-page-actions patches).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Redirect every import of Starlight's Icon component to a wrapper that
references common icons (site chrome, sidebar topics, socials, pickers,
asides) from a hashed /_astro/ sprite via <use>, falling back to inline
markup for any other icon. The sprite is generated from Starlight's icon
set (bun run icon-sprite) and a unit test keeps it in sync.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2216. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2216 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

Astro's scoped class on the component tag replaced the class passed through the
props spread, so icons like the live menu's external-link lost their styling hook.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist

Copy link
Copy Markdown
Member Author

Combined validation: real aspire publish image

I merged #2215, #2214, #2213 and #2216 into the ADO deploy branch locally, then ran the same steps as pipelines/build.yml: bicep restore followed by aspire publish -o .generated (the Ev2 publish step). The resulting image was loaded with docker load and run as a container in Production mode with Redis.

Before After all four PRs
Ev2ServiceArtifactsRoot/Images/aspiredev.tar.gz ~4 GB 1.76 GB
Built HTML pages 38,344 29,134
Site output (dist) 9.8 GB 3.73 GB
wwwroot in image n/a 3.73 GB originals + 0.68 GB .br

The container starts in 11 s, /healthz returns 200, and idle memory is about 2 GB, likely from the 134 MB staticwebassets.endpoints.json.

Testing against the container

  • Layout check: 35 representative layouts (docs, splash, hub, 404, /de/ fallback, /ja/ translated, C#/TS/Go API landing, package, type and member pages) on desktop and mobile. Every page returned the expected status, with no failed requests and no page errors.
  • Full Playwright suite, CI=1 bunx playwright test, all 3 projects, reusing the container on :4322: 1,632 passed, 5 failed, 2 flaky, 107 skipped. Failures are triaged below.
  • Manual testing of the running container found no issues.
    This PR: docs pages drop about 85 KB each (install-cli went from 260 KB to 175 KB, with 0 inline styles and about 6 KB of inline script). Two issues found in the combined run:
  1. Inline-fallback icons lost the caller's class (Astro's scoped class replaces the spread class), so the live menu's external-link icons broke (live-status.spec.ts:703). Fix: pass class={Astro.props.class} explicitly (coordinator commit 8ba6fcce, being applied here).
  2. api-search-contract.spec.ts:248 deadlocks: the test holds back every script, and the pre-paint bootstraps are now render-blocking <script src>. Being resolved in this PR.

Only the AppHost-preference bootstrap still blocks rendering as an
external script. The WCP bootstrap only needs the parsed DOM, so it now
loads with defer; its one pre-paint step (hiding cookie controls when a
previous visit found consent isn't required) is a tiny inline snippet.

The API search contract test now holds back only module scripts, as
intended, instead of the classic pre-paint bootstrap that blocks parsing.
Also cover the inline-fallback icon class regression in a unit test.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review November 20, 2026 18:12
Copilot AI balanced review requested due to automatic review settings November 20, 2026 18:12
@IEvangelist
David Pine (IEvangelist) merged commit 3e38141 into main Nov 20, 2026
20 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the dapine-microsoft-externalize-inline-page-assets branch November 20, 2026 18:12

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The page-wide Icon and asset/script changes lack confirmed standalone production CI and built-site validation, while the supplied browser results mainly cover dev mode or a combined-series image.

No open issues 🎉

What changed in this PR

This PR reduces repeated HTML in the aspire.dev static site by moving shared scripts, styles, and icons into cacheable assets, supporting the effort to shrink the frontend container image.

Changes:

  • Externalizes preference and consent bootstraps and bundles footer and OS-aware tab behavior.
  • Adds a shared icon sprite and replaces repeated sidebar and page-action SVGs with CSS masks.
  • Updates build settings, generation tooling, and tests for shared-asset delivery.
File Description
src/​frontend/​tests/​unit/​navigation-preferences.vitest.test.ts Checks external, blocking preference initialization.
src/​frontend/​tests/​unit/​icon-sprite.vitest.test.ts Covers sprite consistency, references, and inline fallback classes.
src/​frontend/​tests/​unit/​custom-components.vitest.test.ts Updates sprite and tab-marker assertions.
src/​frontend/​tests/​e2e/​api-search-contract.spec.ts Allows pre-paint scripts through the controller gate.
src/​frontend/​src/​utils/​icon-sprite.ts Defines shared icons and sprite generation helpers.
src/​frontend/​src/​scripts/​wcp-consent.inline.js Extracts the consent bootstrap into an external asset.
src/​frontend/​src/​scripts/​os-aware-tabs.ts Centralizes OS-based shell-tab defaults.
src/​frontend/​src/​scripts/​apphost-preferences.inline.js Restores preferences and seeds the terminal default before paint.
src/​frontend/​src/​components/​starlight/​Icon.astro Uses sprite references with an inline fallback.
src/​frontend/​src/​components/​starlight/​Head.astro Loads external bootstraps while retaining minimal pre-paint consent logic.
src/​frontend/​src/​components/​starlight/​Footer.astro Bundles footer behavior and removes ineffective browser translation code.
src/​frontend/​src/​components/​OsAwareTabs.astro Supplies sync-key markers to the shared initializer.
src/​frontend/​src/​assets/​icons/​starlight-icons.sprite.svg Adds the generated shared icon sprite.
src/​frontend/​scripts/​generate-icon-sprite.ts Generates the sprite from installed Starlight icons.
src/​frontend/​patches/​starlight-page-actions@0.7.0.patch Replaces external-link SVGs with CSS masks.
src/​frontend/​patches/​README.md Documents the expanded patch purposes.
src/​frontend/​patches/​@astrojs__starlight@0.41.3.patch Replaces sidebar caret SVGs with CSS masks.
src/​frontend/​package.json Adds the sprite-generation command.
src/​frontend/​eslint.config.mjs Configures linting for classic browser scripts.
src/​frontend/​config/​starlight-icon-sprite.mjs Redirects Starlight icon imports to the wrapper.
src/​frontend/​astro.config.mjs Registers the wrapper plugin and externalizes scripts, sprite, and stylesheets.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants